/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.hadoop.mapreduce.checkpoint;

import java.io.IOException;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;

/**
 CheckpointService 提供了一个简单的 API 来存储和检索任务的状态。
 CheckpointService是原子的、单写入器、一次写入、多读取器、准备好多种类型的对象。
 这是通过仅在提交CheckpointService时释放检查点的 CheckpointID 并防止重新打开CheckpointService以进行写入来提供的。
 非功能性属性，例如持久性、可用性、压缩、垃圾收集、配额留给 实现。
 此 API 被设想为CheckpointService服务的基本构建块，在其上可以分层更丰富的接口（例如，提供对象序列化、检查点元数据和出处等的框架）
 *
 */

/**
 * The CheckpointService provides a simple API to store and retrieve the state of a task.
 *
 * Checkpoints are atomic, single-writer, write-once, multiple-readers,
 * ready-many type of objects. This is provided by releasing the CheckpointID
 * for a checkpoint only upon commit of the checkpoint, and by preventing a
 * checkpoint to be re-opened for writes.
 *
 * Non-functional properties such as durability, availability, compression,
 * garbage collection, quotas are left to the implementation.
 *
 * This API is envisioned as the basic building block for a checkpoint service,
 * on top of which richer interfaces can be layered (e.g., frameworks providing
 * object-serialization, checkpoint metadata and provenance, etc.)
 *
 */

public interface CheckpointService {

  public interface CheckpointWriteChannel extends WritableByteChannel { }
  public interface CheckpointReadChannel extends ReadableByteChannel { }
  /**
   *此方法创建一个检查点并提供一个写入检查点的通道,此时用户还不知道检查点的名称/位置,实际上,
   * 在调用commit之前，CheckpointID不会被释放给用户
   *这使得执行写的原子性很容易
   * //就是写操作没完成不释放
   /**
   * This method creates a checkpoint and provide a channel to write to it. The
   * name/location of the checkpoint are unknown to the user as of this time, in
   * fact, the CheckpointID is not released to the user until commit is called.
   * This makes enforcing atomicity of writes easy.
   * @return a channel that can be used to write to the checkpoint//可用于写入检查点的通道
   * @throws IOException
   * @throws InterruptedException
   */
  public CheckpointWriteChannel create()//创建检查点写入通道
          throws IOException, InterruptedException;
/**
 * 用于完成和现存的检查点，它返回CheckpointID
 * 后面可以用来访问(只读)这个检查点。这个保证
 * 检查点的原子性。
 */
  /**
   * Used to finalize and existing checkpoint. It returns the CheckpointID that
   can be later used to access (read-only) this checkpoint. This guarantees
   atomicity of the checkpoint.
   * @param ch the CheckpointWriteChannel to commit//要提交的CheckpointWriteChannel
   * @return a CheckpointID
   * @throws IOException
   * @throws InterruptedException
   */
  public CheckpointID commit(CheckpointWriteChannel ch)
          throws IOException, InterruptedException;
/**
 *双重提交,它将中止当前检查点,不会生成CheckpointID
 也不释放给用户，因此检查点是不可访问的
 */
  /**
   * Dual to commit, it aborts the current checkpoint. Garbage collection
   choices are left to the implementation. The CheckpointID is not generated
   nor released to the user so the checkpoint is not accessible.
   * @param ch the CheckpointWriteChannel to abort//要终止的检查点通道
   * @throws IOException
   * @throws InterruptedException
   */
  public void abort(CheckpointWriteChannel ch)
          throws IOException, InterruptedException;
/**
 * 给定一个CheckpointID返回一个读通道
 */
  /**
   * Given a CheckpointID returns a reading channel.
   * @param id CheckpointID for the checkpoint to be opened//要打开的检查点的CheckpointID
   * @return a CheckpointReadChannel//一个读通道
   * @throws IOException
   * @throws InterruptedException
   */
  public CheckpointReadChannel open(CheckpointID id)//
          throws IOException, InterruptedException;

  /**
   * It discards an existing checkpoint identified by its CheckpointID.//它丢弃由其CheckpointID标识的现有检查点。
   * @param  id CheckpointID for the checkpoint to be deleted
   * @return a boolean confirming success of the deletion确认删除成功的布尔值
   * @throws IOException
   * @throws InterruptedException
   */
  public boolean delete(CheckpointID id)
          throws IOException, InterruptedException;

}
